home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 329_01 / regexp.doc < prev    next >
Text File  |  1988-11-11  |  10KB  |  264 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.           REGEXP (3)                 local                  REGEXP (3)
  68.  
  69.  
  70.      NAME         NAME  
  71.  
  72.           regcomp,  regexec,  regsub,  regerror  -  regular expression
  73.           handler 
  74.  
  75.      SYNOPSIS         SYNOPSIS  
  76.  
  77.           #include <regexp.h>
  78.           
  79.           regexp *regcomp(exp)
  80.           char *exp;
  81.           
  82.           int regexec(prog, string)
  83.           regexp *prog;
  84.           char *string;
  85.           
  86.           regsub(prog, source, dest)
  87.           regexp *prog;
  88.           char *source;
  89.           char *dest;
  90.           
  91.           regerror(msg)
  92.           char *msg;
  93.  
  94.      DESCRIPTION         DESCRIPTION  
  95.  
  96.                                           egrep    1  style                       These   functions   implement   egrep   (1)-style    regular
  97.           expressions and supporting facilities.  
  98.  
  99.           Regcomp                                                                 Regcomp  compiles  a  regular expression into a structure of
  100.                regexp                                                             type regexp , and returns a pointer to it.   The  space  has
  101.                                   malloc   3                                      been  allocated  using  malloc  (3)  and  may be released by
  102.           free               free.  
  103.  
  104.           Regexec                                string                           Regexec  matches  a  NUL-terminated    string  against   the
  105.                                               prog                                compiled regular  expression  in    prog.   It returns 1 for
  106.           success and 0 for  failure,  and  adjusts  the  contents  of
  107.           prog s startp and  endp                                       prog's startp and  endp (see below) accordingly.  
  108.  
  109.                                regexp                                             The  members  of  a  regexp  structure  include at least the
  110.           following (not necessarily in order): 
  111.  
  112.           char *startp[NSUBEXP]; 
  113.           char *endp[NSUBEXP]; 
  114.  
  115.                 NSUBEXP                                                            where NSUBEXP is defined (as 10) in the header file.  Once a 
  116.                       regexec                            regexp                   successful  regexec has been done using the    regexp,  each
  117.           startp endp                                          string              startp/endp pair describes one substring within the  string, 
  118.                        startp                                                     with  the    startp  pointing  to the first character of the
  119.                              endp                                                 substring and the  endp  pointing  to  the  first  character
  120.           following the substring.  The 0th substring is the substring 
  121.                string                                                             of   string  that matched the whole regular expression.  The
  122.           others  are  those  substrings  that  matched  parenthesized
  123.           expressions    within    the    regular   expression,   with
  124.           parenthesized expressions numbered in left-to-right order of 
  125.           their opening parentheses.  
  126.  
  127.           Regsub copies source to dest, making substitutions according 
  128.  
  129.  
  130.                                       -1-
  131.  
  132.  
  133.           REGEXP (3)                 local                  REGEXP (3)
  134.  
  135.  
  136.           to the most recent  regexec  performed  using  prog.    Each
  137.           instance  of  `&'  in    source is replaced by the substring
  138.           indicated by startp[0] and endp[0].  Each instance  of  `n',
  139.           where  n  is a digit, is replaced by the substring indicated
  140.           by startp[n] and endp[n].  
  141.  
  142.           Regerror is called whenever an error is detected in regcomp, 
  143.           regexec, or regsub.  The default regerror writes the  string
  144.           msg,  with  a suitable indicator  of origin, on the standard
  145.                                              Regerror                             error output and invokes exit(2).  Regerror can be  replaced
  146.           by the user if other actions are desirable.  
  147.  
  148.      REGULAR EXPRESSION SYNTAX         REGULAR EXPRESSION SYNTAX  
  149.  
  150.           A  regular expression is zero or more branches, separated by
  151.           `|'.  It matches anything that matches one of the branches.  
  152.  
  153.           A branch is zero or more pieces, concatenated.  It matches a 
  154.           match for the first, followed by a  match  for  the  second,
  155.           etc.  
  156.  
  157.           A  piece  is  an atom possibly followed by `*', `+', or `?'.
  158.           An atom followed by `*' matches a  sequence  of  0  or  more
  159.           matches of  the  atom.    An  atom followed by `+' matches a
  160.           sequence of 1 or more matches of the atom.  An atom followed 
  161.           by `?' matches a match of the atom, or the null string.  
  162.  
  163.           An atom is a regular expression in parentheses  (matching  a
  164.           match  for the regular expression), a range (see below), `.'
  165.           (matching any single  character),  `^'  (matching  the  null
  166.           string  at the beginning of the input string), `$' (matching
  167.           the null string at the end  of  the  input  string),  a  `\'
  168.           followed by a single character (matching that character), or 
  169.           a single character with no other significance (matching that 
  170.           character).  
  171.  
  172.           A range  is  a  sequence of characters enclosed in `[]'.  It
  173.           normally matches any single character from the sequence.  If 
  174.           the  sequence  begins  with  `^',  it  matches  any   single
  175.           character not  from  the  rest  of  the  sequence.    If two
  176.           characters in the sequence are separated  by  `-',  this  is
  177.           shorthand for the full list of ASCII characters between them 
  178.           (e.g. `[0-9]'  matches  any  decimal  digit).   To include a
  179.           literal `]' in the sequence, make  it  the  first  character
  180.           (following a  possible `^').  To include a literal `-', make
  181.           it the first or last character.  
  182.  
  183.      AMBIGUITY         AMBIGUITY  
  184.  
  185.           If a regular expression could match two different  parts  of
  186.           the  input  string,  it  will  match  the  one  which begins
  187.           earliest.  If  both  begin  in  the  same  place  but  match
  188.           different  lengths,  or  match  the same length in different
  189.           ways, life gets messier, as follows.  
  190.  
  191.           In general, the possibilities in  a  list  of  branches  are
  192.           considered  in  left-to-right  order,  the possibilities for
  193.           `*', `+',  and  `?'  are  considered  longest-first,  nested
  194.  
  195.  
  196.                                       -2-
  197.  
  198.  
  199.           REGEXP (3)                 local                  REGEXP (3)
  200.  
  201.  
  202.           constructs   are  considered  from  the  outermost  in,  and
  203.           concatenated constructs are considered leftmost-first.   The
  204.           match  that will be chosen is the one that uses the earliest
  205.           possibility in the first choice that has to  be  made.    If
  206.           there  is more than one choice, the next will be made in the
  207.           same manner (earliest possibility) subject to  the  decision
  208.           on the first choice.  And so forth.  
  209.  
  210.           For  example,  `(ab|a)b*c'  could  match `abc' in one of two
  211.           ways.  The first choice is between `ab' and `a'; since  `ab'
  212.           is  earlier, and does lead to a successful overall match, it
  213.           is chosen.  Since the `b' is already spoken  for,  the  `b*'
  214.           must match its last possibility\(emthe empty string\(emsince 
  215.           it must respect the earlier choice.  
  216.  
  217.           In  the  particular case where no `|'s are present and there
  218.           is only one `*', `+', or `?', the net  effect  is  that  the
  219.           longest possible  match will be chosen.  So `ab*', presented
  220.           with `xabbbby', will match `abbbb'.  Note that if  `ab*'  is
  221.